home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
LAN
/
FAXPAK.ARJ
/
FPNSTE.EXE
/
FPNSHARE.DOC
< prev
next >
Wrap
Text File
|
1991-08-01
|
109KB
|
3,096 lines
F A X P a k N e t S h a r e (version 2)
Copyright Jeff Hofstetter 1990-1991
All Rights Reserved
Jeff Hofstetter
1722 Drake Street
Longmont, Colorado 80503
USA
phone: 303.440.7683
Intel fax board line: 303.440.7683
Compulsive ID: 70365,110
TABLE OF CONTENTS
CHAPTER 1 - Introduction..............................1
FAX SERVER..........................................1
CLIENT PROGRAMS.....................................2
FEATURES............................................2
UPDATING FROM THE PREVIOUS VERSION..................3
CHAPTER 2 - Installation..............................4
REQUIREMENTS........................................4
HARDWARE RECOMMENDATIONS............................4
GETTING STARTED.....................................5
AFTER THE INSTALLATION..............................6
CHAPTER 3 - Running the Fax Servers...................7
FPNSHARE.EXE - THE DEDICATED FILE SERVER............7
FPNSHARE.LOG - HISTORY FILE......................8
OPTIONS MENU.....................................8
FPNSTSR.EXE - THE NON-DEDICATED SERVER..............9
FPNSTSR.LOG - HISTORY FILE......................10
CHAPTER 4 - FPNETFAX and FPNETLOG....................11
CHAPTER 5 - Customizing for your Network.............12
INITIALIZATION FILES (.INI files)..................12
LOCATION OF .INI FILES..........................13
PARAMETER REPLACEMENT IN .INI FILES.............13
.INI FILE COMMANDS.................................14
FPNSHARE.INI....................................14
FPNSTSR.INI.....................................20
FPNETLOG.INI....................................22
FPNETFAX.INI....................................25
CHAPTER 6 - Standard Files...........................29
CHAPTER 7 - Integrating External Programs............30
EXTERNAL PROGRAM REQUIREMENTS......................30
HOW FPNSHARE.EXE RUN AN EXTERNAL PROGRAM...........31
INFO REQUIRED TO INTEGRATE AN EXTERNAL PROGRAM.....31
MODIFYING THE FPNSHARE.INI FILE....................32
CONVERT= entry..................................32
PRINT= entry....................................33
EXAMPLE .INI ENTRIES...............................33
TROUBLESHOOTING EXTERNAL PROGRAMS..................35
APPENDIX A - Customer Information....................36
COPYRIGHT..........................................36
LICENSE............................................36
WARRANTY...........................................36
CUSTOMER SUPPORT...................................36
APPENDIX B - PROGRAMMING INTERFACE...................38
GENERAL INFORMATION................................38
FAX CONTROL FILES..................................39
FILE= ENTRIES IN THE FAX CONTROL FILE..............42
FAXPAK NETSHARE LOG FILES..........................43
C H A P T E R 1
I N T R O D U C T I O N
────────────────────────────────────────────────────────────
FAXPak(tn) NetShare allows shared access to an Intel
fax board (either the Connection Coprocessor or the
SatisFAXtion board) across a local area network.
The software consists of two parts: a "server" program
and "client" programs.
FAX SERVER
The server software (fpnshare.exe or fpnstsr.exe) runs
on the PC containing the fax board. The server may be
either dedicated or non-dedicated.
A PC running the dedicated server performs only the fax
server function. A non-dedicated one may be used for
other purposes while the server function is being
performed.
A dedicated server is best for most installations. If
your fax volume is low and you MUST use the PC for
other functions, then you will need to use fpnstsr.exe.
You lose the following features when using the non-
dedicated server:
o Incoming faxes are NOT handled by FAXPak NetShare.
o Efficient handling of outgoing faxes is not enabled.
o Files are faxed directly from the network drive. This
MAY NOT work with some installations. Normally, the
Intel fax software expects the files to be faxed to
reside on the same drive as the fax software
(typically C:). If this is not the case, the Intel
software may report an error 0302 or 0303 (file/path
not found). The dedicated server solves this anomaly
by copying the file from the network drive to the
local hard disk before faxing.
o No pending log is available to network PK.
o Current fax board status is not available from work
stations.
Compatibility problems with non-dedicated server. Since
fpnstsr.exe is a TSAR program, the possibility exists
for conflicts with other software you might be using.
────────────────────────────────────────────────────────────
1
Chapter 1 Introduction
────────────────────────────────────────────────────────────
If a conflict occurs, the fax PC could "lock up" and
require a re-boot. Also, if the person using the PC
with the fax board turns off the PC, the network fax
process is not longer running.
CLIENT PROGRAMS
The client software (fpnetfax.exe and fpnetlog.exe) are
run by each user on the network to send faxes or to
view the results of faxes.
fpnetfax is used to send faxes and fpnetlog is used to
view the fax log.
FEATURES
o All users on the network can send faxes from their
own work stations. No need to hike up to the fax
machine and stand in line!.
o View fax logs from all work stations. Network-wide
logs, group logs, or individual logs are all
supported.
o "Phone books" allow users to create lists of
frequently called fax numbers. No limit on how many
phone books may be created. Public and private phone
books are supported.
o Send the same fax to multiple addressees.
o Send faxes in normal or high resolution mode. If
sending to someone with an Intel fax board, files can
be sent directly without converting to "fax" files.
This also allows any type of computer file to be sent
to another Intel fax board user.
o Incoming faxes can be saved to a specific directory
for manual processing. Faxes are automatically
converted to DCX (Intel fax format) files and saved
as DOS files. File transfers from other users with
Intel fax boards are saved under the ORIGINAL FILE
name to a specific directory if desired.
o The dedicated version allows external programs to run
when a fax is received AND before an outgoing fax is
scheduled. This "open architecture" allows other
────────────────────────────────────────────────────────────
2
Introduction Chapter 1
────────────────────────────────────────────────────────────
programs to be integrated into the server for
printing of received faxes and for converting
documents to a "faxable" format before actually being
sent.
UPDATING FROM THE PREVIOUS VERSION
The previous version (called faxshare.exe) has been
replaced by this version. Although the concepts are
similar, they are completely different programs.
The previous programs faxshare.exe and faxsend.exe have
been replaced by fpnshare.exe and fpnetfax.exe. The old
.cfg files will not work with the new version, however,
the new programs have similar commands.
────────────────────────────────────────────────────────────
3
C H A P T E R 2
I N S T A L L A T I O N
────────────────────────────────────────────────────────────
REQUIREMENTS
o Your Intel fax board must be installed and
operational BEFORE installing FAXPak NetShare! Verify
that you can send a fax using the Intel program
fax.exe (or connect.exe).
o On the PC with the fax board, you will need to have
the Intel program chasm.exe or scam.exe running.
FAXPak NetShare communicates with the fax board
through this "SASS" manager.
o Do NOT run the Intel program faxpop.exe along with
the fax server.
o Disk space requirements are small, but once the fax
process begins, you will need to keep an eye on how
much space is being used.
o The fax server process will operate on most IBM
compatibles. The server program requires
approximately 128k of memory while running.
o The client programs (fpnetfax.exe and fpnetlog.exe)
may require up to 256k of memory depending on how big
the log files you are looking at are.
HARDWARE RECOMMENDATIONS
To get the best performance from FAXPak NetShare, the
fax server PC should have (as a minimum) a 80286 CPU
(12Mhz or faster). If you plan to integrate any
external programs, you should have at least 256K of
EXPANDED memory available for swapping the server
program. Also, you will need to meet whatever
requirements the external program may have. File
conversion software generally requires lots of memory
(possibly EXPANDED or EXTENDED).
A hard disk drive of 40MB is the smallest you should
consider (unless you have a light fax load). The faster
the hard disk, the better.
If you have extra memory, a good disk cache program
will also help speed up the entire fax process.
User PCs don't have any special hardware requirements.
────────────────────────────────────────────────────────────
4
Installation Chapter 2
────────────────────────────────────────────────────────────
GETTING STARTED
Your floppy diskette contains an installation program
that helps you get started. Be sure to install from the
PC that contains your fax board and also be sure to be
logged in to your network as the supervisor -- or any
other user name that has sufficient network rights to
create directories, create files, etc.
To begin the installation process simply insert the
floppy disk and type...
A:INSTALL <enter>.
If your floppy disk drive is B (or another letter),
substitute the correct drive letter.
Follow the directions on the screen to complete the
install process. You can press the PH key during the
install process to read helpful information.
The install process performs the following steps:
o Copies the server program(s) fpnshare.exe and/or
fpnstsr.exe to the local hard disk of the fax PC. The
.INI (initialization) files are also created with
default settings.
o Creates a FAXPak NetShare home directory on a network
drive then creates the following sub-directories:
IN
OUT
LOG
REQ
o A sample phone book file (default.fsb) is copied to
the FAXPak home directory.
o The user programs (fpnetfax.exe and fpnetlog.exe)
along with their help files and .INI files are copied
to a network "public" directory.
The install process DOES NOT make any modifications to
your config.sys or autoexec.bat files.
────────────────────────────────────────────────────────────
5
Chapter 2 Installation
────────────────────────────────────────────────────────────
AFTER THE INSTALLATION
Once the files are copied to your network you still
have a few things to do. You must make sure that the
FAXPak NetShare home directory is accessible by all
users. This generally means that you must assign all
users adequate network rights to read files, delete
files, create files.
You should also verify that the user programs
(fpnetfax.exe and fpnetlog.exe) are accessible to all
users.
The install process creates the required initialization
files (.INI) with default values but you will want to
read the document section that describes the .INI files
in detail to see if you need or want to modify the
default setup.
If you are using the dedicated server, you will want to
create a special network "user" login for the fax
server process. You can then have the fax server
automatically log in to the network by putting the
required network login commands in the autoexec.bat
file of the server PC. The server PC needs to have ALL
network rights in the network fax home directory and
all sub-directories.
────────────────────────────────────────────────────────────
6
C H A P T E R 3
R U N N I N G T H E F A X S E R V E R S
────────────────────────────────────────────────────────────
Once you have run the installation procedure, you are
ready to begin testing the network fax process. You
should run several tests to insure that you are getting
the results you expect.
It is particularly helpful to have a local fax machine
that you can send test faxes to while you are testing.
Fpnshare.exe is the dedicated fax server program. It
provides fax services to the other PCs on the network
by accepting fax requests from users, submitting the
fax jobs to the fax board, then logging the results of
the faxes in fax log files.
Fpnstsr.exe is the non-dedicated server program. It
provides similar services to the network, ex as the
dedicated server. It can't handle as large a fax load,
plus it lacks some features.
FPNSHARE.EXE - THE DEDICATED FILE SERVER
To start the network fax server (on the PC with the fax
board):
o Log in to the network using the fax server user name
you created.
o Change to the C:\FAXPAK directory (or a different
directory if you did not accept the default directory
name).
o Type FPNSHARE <enter>
The Fpnshare.ini file is loaded and each line is
processed. If any invalid .INI file entries are found,
an error message is displayed and Fpnshare.exe does not
run. You will need to correct these problems before you
can begin any faxing!
If the .INI file is processed successfully,
Fpnshare.exe then checks to see if there are any faxes
that were scheduled in a previous session. If any are
found, they are reloaded and re-scheduled as
appropriate.
────────────────────────────────────────────────────────────
7
Chapter 3 Running the Fax Servers
────────────────────────────────────────────────────────────
FPNSHARE.LOG - HISTORY FILE
Fpnshare.exe records important information in a
"history" file called FPNSHARE.LOG. This file will be
created and maintained in the network fax log directory
(by default this is \FAXPAK\LOG on a network drive).
Each time Fpnshare.exe runs, it checks this log file
and if it has become large, a warning message is
displayed and Fpnshare.exe does not run. When this
happens, you should rename the FPNSHARE.LOG file to a
different name OR delete it. This log file is a plain
text file and may be typed to the screen or printed if
desired.
OPTIONS MENU
The Fpnshare.exe screen displays information about any
current faxing activity, number of faxes waiting to be
sent, and a scrolling list of messages. Pressing the
ESC key displays an Options Menu with the following
choices:
Stop the fax server
List pending sends
Cancel current send
Display on/off
Cancel all pending
Test fax board(s)
You can select an option by moving the highlight bar up
or down then pressing ENTER or you can press the
highlighted letter. Each of the options is explained
next. If you fail to make a selection from the menu
within about 30 seconds, the menu is cancelled.
STOP THE FAX SERVER select with "S"
-------------------------------------------------------
When you select this option you are asked to verify the
selection. If you elect to stop the server, the program
ends. Any faxes waiting to be sent WILL NOT BE SENT
until the server is re-started.
────────────────────────────────────────────────────────────
8
Running the Fax Servers Chapter 3
────────────────────────────────────────────────────────────
LIST PENDING SENDS select with "L"
-------------------------------------------------------
A brief list of all faxes waiting to be sent will be
displayed in the message window.
CANCEL CURRENT SEND select with "C"
-------------------------------------------------------
If there is a fax currently being sent, it will be
stopped. This may take several seconds to occur.
DISPLAY ON/OFF select with "D"
-------------------------------------------------------
You can have FPNSHARE blank the display screen while it
is running. This may prevent monitor "burn in". Each
time you select this option, the screen display is
toggled on and off.
CANCEL ALL PENDING SENDS select with "A"
-------------------------------------------------------
If you wish to cancel all pending faxes choose this
option. All faxes waiting to be sent will be deleted.
There is no way to recover deleted faxes, they must be
re-submitted. This option prompts for verification
before proceeding.
TEST FAX BOARD(S) select with "T"
-------------------------------------------------------
This performs a quick diagnostic on the fax board.
Results are shown in the message window.
FPNSTSR.EXE - THE NON-DEDICATED SERVER
To start the network fax server (on the PC with the fax
board):
Log in to the network
Change to the C:\FAXPAK directory (or a different
directory if you did not accept the default
directory name).
────────────────────────────────────────────────────────────
9
Chapter 3 Running the Fax Servers
────────────────────────────────────────────────────────────
Type FPNSTSR <enter>
You will see a brief sign-on message and a list of the
current server settings. At this point, the server
loads into the PC's memory and starts running. You may
then use the PC for other programs.
If you wish to stop the server program, exit from any
program you are running. Then, at the DOS prompt, type
FPNSTSR -U <enter>
to unload the server program. If you loaded any other
TSR programs AFTER the server program, you won't be
able to unload it. You must first unload the other TSR
programs.
FPNSTSR.LOG - HISTORY FILE
Fpnstsr.exe maintains a history log file of important
messages/events. This file is called FPNSTSR.LOG and is
created and maintained in the fax server PC directory
where the Intel fax software was installed. This is
normally C:\FAX for a SatisFAXtion board or C:\CONNECT
for a Connection CoProcessor. If you installed your
software in a different directory, that directory will
be used.
You should read or print this log file from time to
time. After you have done that, either delete or rename
the file to prevent the file from becoming too large.
────────────────────────────────────────────────────────────
10
C H A P T E R 4
F P N E T F A X and F P N E T L O G
────────────────────────────────────────────────────────────
Fpnetfax.exe is run by users to create a fax request
which will be processed by the fax server. Fpnetlog.exe
is used to view the fax logs. Both of these programs
have help screens that provide information about the
various functions available. Run either of the programs
and press the PH key to access the help information.
────────────────────────────────────────────────────────────
11
C H A P T E R 5
C U S T O M I Z I N G F A X P A K N E T S H A R E
────────────────────────────────────────────────────────────
The install process creates a "standard" setup. Once
you have become familiar with the basic operations of
FAXPak NetShare, you will want to customize the
programs to meet your individual requirements.
To customize FAXPak NetShare, you will need to have
some form of text editor (or word processor). You
should have a good general knowledge of DOS functions
(especially as relates to DOS environment variables,
the DOS PATH function, and the DOS "SET" command).
You also need a good understanding of your network
setup and environment.
INITIALIZATION FILES (.INI files)
All FAXPak NetShare programs are controlled by using an
initialization file. These files have the same file
name as the program except that the file extension is
.INI. For example, fpnshare.ini controls fpnshare.exe.
An .INI file is a plain text file and may be modified
using any text editor. A word processor may be used as
long as the file is saved to the disk in plain text
format. No word processing format codes are allowed.
An .INI file consists of several lines of control
commands. Each line has only one command. Commands
consists of a key word and a command value separated by
an equal ("=") sign. For example:
LogDir = F:\FAXPAK\LOG
In this case "LogDir" is the key word, "F:\FAXPAK\LOG"
is the value. Leading and trailing spaces are removed
from the key word and the key value so that you may use
spaces to make the file more readable.
Any line that has a semi-colon (";") as the first NON-
SPACE character is ignored. This allows you to add
comments in the .INI file.
Key words and values may be entered in UPPER CASE,
lower case, or Mixed CASE. For example:
LOGDIR = F:\FAXPAK\LOG
logdir = f:\faxpak\log
LogDir = F:\Faxpak\Log
────────────────────────────────────────────────────────────
12
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
are all equivalent.
LOCATION OF .INI FILES
fpnshare.ini and/or fpnstsr.ini must be located in the
same directory as the .EXE files.
fpnetlog.ini and fpnetfax.ini may be located in
different directories depending on how you want to use
them. In general, when these programs start, they
search for the .INI files in the following places
(listed by search order):
o The current directory
o Each directory listed in the DOS PATH
o The directory where the .EXE file is located.
This method allows you to create more than one .INI
file and control how the program behaves. You may want
to create a separate .INI file for each user and
specify unique control commands in each one.
PARAMETER REPLACEMENT IN .INI FILES
NOTE: This only applies to the .INI files for FPNETFAX
and FPNETLOG!
In addition to the ability to have multiple .INI files,
you may use "parameter replacement" in the .INI file to
customize the operation. Parameter replacement allows
the VALUES in an .INI file to be copied from DOS
ENVIRONMENT VARIABLES. For example:
LogFile = %UID%
In this case, when the program is run, it reads the
.INI file and while processing this line, it tries to
find a DOS ENVIRONMENT variable "UID". If it finds it,
it replaces the "%UID%" text with the text from the DOS
variable.
DOS ENVIRONMENT variables are assigned using the DOS
command
SET varname=value
────────────────────────────────────────────────────────────
13
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
You can type these commands at the DOS command line or
you can include them in DOS batch files (like
AUTOEXEC.BAT). To expand on the above example, if you
had typed this:
SET UID=JEFF
and then run FPNETLOG, the .INI file would be processed
as if the command line were
LogFile = JEFF
This parameter replacement feature allows you to create
a single .INI file for all users but still customize
certain features of the operation by using DOS
variables.
Note that DOS environment variables are very touchy
about using extra spaces. Do NOT include spaces before
or after the equal sign. For example:
*** WRONG *** SET UID = JEFF
*** RIGHT *** SET UID=JEFF
.INI FILE COMMANDS
Below is a complete list and explanation of all valid
commands for FAXPak NetShare .INI files.
FPNSHARE.INI
REQDIR = directory REQUIRED
-------------------------------------------------------
The NETWORK directory name where all fax requests are
created. This entry is common to all .INI files and
must be identical in each one.
Example: ReqDir = F:\FAXPAK\REQ
LOGDIR = directory REQUIRED
-------------------------------------------------------
This is the NETWORK directory where FPNSHARE will
create and maintain fax logs (and the "error" log).
────────────────────────────────────────────────────────────
14
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
Example: LogDir = F:\FAXPAK\LOG
FAXEXT = ext default = FAX
-------------------------------------------------------
The file EXTENSION used to identify fax requests. This
should normally NOT be changed. This entry also appears
in FPNETFAX.INI and that setting MUST be the same as
this one. DO NOT include the period.
Example: FaxExt = FAX
COVERDIR = directory default = none
-------------------------------------------------------
This directory controls whether or not the cover sheet
text (if any) for OUTGOING faxes is saved in a disk
file for historical purposes. If you include this entry
in FPNSHARE.INI, then any cover sheet text will be
stored in files in this directory. These files will
have the file extension .CVR to identify them. Also,
when you view the log for this event, you will see the
file name of the cover sheet.
INTERVAL = #seconds default = 60 seconds
-------------------------------------------------------
Specifies the number of SECONDS between searches for
fax requests. If this number is too low, then excessive
network traffic will be generated. On a busy system, 10
seconds may be a good starting point.
Example: Interval = 120
SIGNAL = frequency default = 0
-------------------------------------------------------
If this number is greater than 0, then a tone of that
frequency will be sounded each time FPNSHARE looks for
fax requests. This is mainly used for initial testing.
Example: Signal = 1000
────────────────────────────────────────────────────────────
15
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
MINIMUMRETRY = number default = 0
-------------------------------------------------------
This number will be used to determine how many times
EVERY fax will be retried. Normally, you should set
this to zero since the users may control the number of
retries on a per fax basis. If this number is greater
than zero, then the actual number of retries will be
the greater of this number and the user-provided
number.
Example: MinimumRetry = 2
RETRYINTERVAL = #seconds default = 300 seconds
-------------------------------------------------------
How many seconds to wait between retry attempts.
Example: RetryInterval = 600
COPYDIR = directory default = none
-------------------------------------------------------
This is the LOCAL FAX SERVER directory where outgoing
files will be temporarily stored. In many cases, the
Intel software does not handle files located on network
drives properly. By making an entry here, the files to
be faxed are copied from the network outbox directory
and actually transmitted from the local hard disk. In
most cases this is the DESIRED operation.
Example: CopyDir = C:\FAXPAK\OUT
RECVDIR = directory default = none
-------------------------------------------------------
This is the NETWORK (or LOCAL) directory where RECEIVED
faxes will be stored.
Example: RecvDir = F:\FAXPAK\IN
────────────────────────────────────────────────────────────
16
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
RECVMODE = NONE, SAVE, PRINT, or BOTH default=none
-------------------------------------------------------
This determines what fpnshare.exe does with INCOMING
faxes. If NONE, then incoming faxes are ignored (but
the Intel software will still be able to handle them).
Note that the incoming faxes are NOT recorded in the
fpnshare.exe logs if RecvMode = NONE!
If SAVE, incoming faxes (and file transfers) are saved
to the RecvDir you provide. The received faxes are also
recorded in the fpnshare logs as appropriate.
If PRINT, incoming faxes will be printed IF you have
enabled an external program to do the printing.
If BOTH, the incoming fax is saved to a disk file AND
printed if you have enabled printing.
Example: RecvMode = SAVE
NOTIFY = command default = none
-------------------------------------------------------
This is a NETWORK message command that will be run when
a fax is RECEIVED. On a Novell network this would be a
"SEND ..." command. On a Lantastic network, it would
be a "NET SEND ..." command. For example:
Novell: Notify = SEND "New fax received" TO FAXADMIN
Lantastic: Notify = NET SEND * "New fax received" *
JEFF
ERRNOTIFY = command default = none
-------------------------------------------------------
This is a NETWORK message command that will be run when
a fax FAILS to complete. Works just like Notify =
Novell example: ErrNotify = SEND "Fax failed" TO
FAXADMIN
────────────────────────────────────────────────────────────
17
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
RECVLOG = filename default = FPNSHARE
-------------------------------------------------------
If you are allowing fpnshare.exe to handle incoming
faxes, the log used to record them will have this name.
Note that the full file name of a log file is composed
of the <RecvDir > + < RecvLog > + .FSL. For example, if
your fpnshare.ini has these entries:
LogDir = F:\FAXPAK\LOG
RecvLog = INCOMING
then the actual file name for the received fax log will
be
F:\FAXPAK\LOG\INCOMING.FSL
Example: RecvLog = INCOMING
SENDLOG = filename ** default = FPNSHARE
-------------------------------------------------------
Normally, the log name for recording OUTGOING faxes is
controlled by the fax request process. If you are
creating your own fax requests by some method other
than fpnetfax.exe, then you are responsible for
assigning a log name for each outgoing fax. You can
specify the name in the fax request or you can make
this SendLog = entry which will apply to any fax
request that does not specify a log file name.
Example: SendLog = OUTGOING
MAXPENDLIST = number default = 25
-------------------------------------------------------
fpnshare.exe maintains a log of faxes waiting to be
sent. This number specifies the maximum number of
entries that will be written in the pending log. This
has NO effect on the number of faxes that are actually
pending. If you set this number very high, you will
find that the time required to write the pending log
may become excessive.
Example: MaxPendList = 40
────────────────────────────────────────────────────────────
18
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
DISPLAYOFF = YES or NO default = NO
-------------------------------------------------------
Setting this to YES will cause the screen display to be
turned off when fpnshare.exe starts.
Example: DisplayOFF = YES
CONVERT = EXT, SAVESCREEN, VERBOSE, program, args
-------------------------------------------------------
If you have an external program that can convert a file
to a Intel faxable file (DCX or PCX), you can integrate
that program with FAXPak NetShare. Please see the
section INTEGRATING OTHER PROGRAM WITH FAXPAK NETSHARE
for more information.
This entry in your .INI file controls the external
program. Replace "EXT" with the file extension of the
type of file you will be converting FROM. Replace
"program" with the name of the program you are
integrating. "args" is replaced by any arguments
required by your external program PLUS the special
symbols "$I" and "$O". These symbols will be removed
from the argument list and replaced by the INPUT file
name to be converted and the OUTPUT file name.
If you include the word SAVESCREEN, then the server
screen display will be saved and the screen will be
cleared before the external program runs. When the
external programs completes, the server screen will be
restored.
If you include VERBOSE, then the time required to run
the external program will be displayed. SAVESCREEN and
VERBOSE are optional.
Position is IMPORTANT in this entry. the file extension
MUST BE FIRST and is required. Next are the optional
SAVESCREEN and/or VERBOSE if desired. Next the external
program name and finally, the external program
arguments plus the "$I" and "$O" symbols.
PRINT = EXT, SAVESCREEN, VERBOSE, program, args
-------------------------------------------------------
This entry is similar to the Convert entry above except
that this external program is run whenever a fax is
received by the server. With the appropriate external
────────────────────────────────────────────────────────────
19
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
program, this entry will allow you to have your
incoming faxes automatically printed when they arrive.
The entry setup is exactly like the Convert entry
except that the "args" entry only uses the "$I" special
symbol (since there is not output file required).
Please see the EXTERNAL PROGRAM section for more
information and examples.
FPNSTSR.INI
REQDIR = directory REQUIRED
-------------------------------------------------------
The NETWORK directory name where all fax requests are
created. This entry is common to all .INI files and
must be identical in each one.
Example: ReqDir = F:\FAXPAK\REQ
FAXEXT = ext default = FAX
-------------------------------------------------------
The file EXTENSION used to identify fax requests. This
should normally NOT be changed. This entry also
appears in fpnetfax.ini and that setting MUST be the
same as this one. DO NOT include the period.
example: FaxExt = FAX
INTERVAL = #seconds default = 60 seconds
-------------------------------------------------------
Specifies the number of SECONDS between searches for
fax requests. If this number is too low, then
excessive network traffic will be generated. On a busy
system, 10 seconds may be a good starting point.
Example: Interval = 60
LOGDIR = directory REQUIRED
-------------------------------------------------------
This is the NETWORK directory where fpnstsr.exe will
create and maintain fax logs (and the "error" log).
────────────────────────────────────────────────────────────
20
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
Example: LogDir = F:\FAXPAK\LOG
LOGFILE = filename REQUIRED
-------------------------------------------------------
The file name (no extension) of the log file where fax
results are recorded.
Example: LogFile = FPSEND
SIGNAL = frequency default = none
-------------------------------------------------------
If Signal is set to something (other than 0), then each
time that fpnstsr.exe looks for outbound faxes, a tone
of this frequency is sounded. Signal = 0 results in NO
beeping.
Example: Signal = 300
ALERTROW = rownumber default = none
-------------------------------------------------------
Another way to indicate that fpnstsr.exe is working. If
you set AlertRow to something (other than 0), then when
fpnstsr.exe checks for outbound faxes, a message will
be displayed on the indicated screen ROW. Setting it to
0 turns OFF the feature.
example: AlertRow = 1
RETRYINTERVAL = #minutes default = 5
-------------------------------------------------------
How long fpnstsr.exe waits before retrying a failed fax
send.
example: RetryInterval = 5
MINIMUMRETRY = number default = none
-------------------------------------------------------
The minimum number of retry attempts that should be
made.
────────────────────────────────────────────────────────────
21
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
example: MinimumRetry = 2
USEEMS = YES or NO default = YES
-------------------------------------------------------
Used to indicate if fpnstsr.exe should try to relocate
most of itself to EXPANDED memory (not EXTENDED
memory!). In addition, fpnstsr.exe may be "loaded high"
if you are using a memory manager that allows this
feature. DOS 5 allows this feature on 386/486 machines.
If fpnstsr.exe is able to use expanded memory, it will
only leave about 7k of memory in normal DOS memory
space (high or low). If you don't have expanded memory,
fpnstsr.exe takes about 16k of memory.
example: UseEMS = YES
FPNETLOG.INI
REQDIR = directory REQUIRED
-------------------------------------------------------
The NETWORK directory name where all fax requests are
created. This entry is common to all .INI files and
must be identical in each one.
Example: ReqDir = F:\FAXPAK\REQ
LOGDIR = directory REQUIRED
-------------------------------------------------------
The NETWORK directory name where all fax logs are
stored.
Example: LogDir = F:\FAXPAK\LOG
LOGFILE = filename REQUIRED
-------------------------------------------------------
When fpnetlog.exe runs, it automatically loads the fax
log specified by this name. (Remember that the full
file name is composed of the <LogDir>+<LogFile>+.FSL).
Normally, each user will have a private log, so this
entry is used to indicate the user's private log. See
the information about DOS environment variables above.
────────────────────────────────────────────────────────────
22
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
Example: LogFile = FPSEND
PRDEVICE = device/file name default = PRN
-------------------------------------------------------
fpnetlog.exe can produce an abbreviated format log
which is suitable for printing. You can specify a
device name OR a file name here to direct the print
output.
Example: PrDevice = PRN
Example: PrDevice = C:\MYDIR\OUTPUT.PRN
PRSTARTUP = text default = none
-------------------------------------------------------
If you want to send a control string to your printer,
you can enter it here. Use the EXACT characters not a
decimal or hex number. For example, to issue a RESET
sequence to an HP laser, your entry is:
Example: PrStartup = {ESC}E
Note the {ESC} symbol is produced by typing the ESC
character.
PRFINISH = text default = none
-------------------------------------------------------
Printer control string to send AFTER the report is
printed.
Example: PrFinish = {ESC}E
PRLINES = number default = 52
-------------------------------------------------------
The number of LOG lines to print on a page. This DOES
NOT include the heading.
Example: PrLines = 70
────────────────────────────────────────────────────────────
23
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
VIEWER = ext, program default = none
-------------------------------------------------------
Format: Viewer = EXT, PROGRAM or Viewer = PROGRAM
You can use the Viewer= entry to specify a file
extension (EXT) and a program name (PROGRAM) to be used
to view files from within the fpnetlog.exe program. For
example, if you have a program called LIST.COM which
you use to display text files, you could have an entry
like this:
Viewer=TXT,LIST.COM
When fpnetlog.exe displays a file name ending with
.TXT, you can press ENTER when that file is highlighted
and fpnetlog.exe will attempt to run your program
LIST.COM.
Multiple Viewer= entries are allowed so that you can
specify different programs for different file types.
An entry like this:
Viewer=MG.COM
will be used to view files that do not match any of the
other Viewer= entries.
Here's a possible fpnetlog.ini viewer= section:
Viewer=TXT,LIST.COM
Viewer=DCX,DCXVIEWER.EXE
Viewer=ARC,ARCV.COM
Viewer=MG.COM
fpnetlog.exe will use LIST.COM to view any .TXT files,
DCXVIEWER.EXE for .DCX files, ARCV.COM for .ARC files,
and MG.COM for all other files.
REVERSESORT = YES or NO default = NO
-------------------------------------------------------
Normally, the log entries are displayed with the oldest
at the top of the list. If you use ReverseSort=YES,
then the most recent faxes will be displayed first.
Example: ReverseSort = NO
────────────────────────────────────────────────────────────
24
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
ALLOWDIR = YES or NO default = YES
-------------------------------------------------------
Normally, a user can select which log to view by using
the OPEN choice on the Options menu. If you wish to
restrict users from viewing any log except for their
own, set AllowDir = NO.
Example: AllowDir = NO
USERID = text default = none
-------------------------------------------------------
This entry may be used to provide some additional
privacy for your users. If this entry is used
(UserID=JEFF for example), then each log entry will be
compared against this entry and if the USERID in the
log entry is different, it will not be displayed. This
is mainly useful if you want to have a common log file
for the entire network. Note that this ALSO affects the
pending log. Users will ONLY see pending entries that
are for their USERID entry.
Example: UserID = JEFFH
FPNETFAX.INI
REQDIR = directory REQUIRED
-------------------------------------------------------
The NETWORK directory name where all fax requests are
created. This entry is common to all .INI files and
must be identical in each one.
Example: ReqDir = F:\FAXPAK\REQ
FAXEXT = ext default = FAX
-------------------------------------------------------
The file EXTENSION used to identify fax requests. This
should normally NOT be changed. This entry also appears
in fpnetfax.ini and that setting MUST be the same as
this one. DO NOT include the period.
Example: FaxExt = FAX
────────────────────────────────────────────────────────────
25
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
LOGFILE = filename REQUIRED
-------------------------------------------------------
The log file name where the results of faxes are
recorded.
Example: LogFile = JEFFH
OUTBOX = directory REQUIRED
-------------------------------------------------------
All files that are to be faxed are COPIED to this
directory prior to being transmitted.
Example: OutBox = F:\FAXPAK\OUT
DEFDIR = directory default = none
-------------------------------------------------------
When a user runs fpnetfax.exe and presses F3 to get a
list of files to send this directory will be the FIRST
directory displayed. The user may then select another
directory.
Example: DefDir = F:\JEFF\DOC
RETRIES = number default = none
-------------------------------------------------------
This setting controls how many times each fax is
retried.
Example: Retries = 5
PREFIX = text (20 char max) default = none
-------------------------------------------------------
If your phone system requires a dialing prefix (for
example to access an outsize line), you can enter the
dialing prefix here and it will be inserted in the
PHONE field.
Example: Prefix = 9,
────────────────────────────────────────────────────────────
26
Customizing FAXPak NetShare Chapter 5
────────────────────────────────────────────────────────────
FAXTYPE = FAX FINE,FAX STD,or FILE TRF default=FAX STD
-------------------------------------------------------
This setting controls the "default" transmission type.
The user has the ability to change the type.
Example: FaxType = FAX FINE
LOGO = full filename default = none
-------------------------------------------------------
If you want a specific logo file to appear on the cover
page of your faxes, you specify the complete file name
here.
NOTE: this file must be the requirements for a "logo"
file as described in the Intel documentation (basically
it must be a PCX file, no color, approx 1/3 of a page
in size).
Example: Logo = C:\LOGOS\JEFFH.PCX
PHONEBOOK = full file name default = none
-------------------------------------------------------
This is the FULL FILE NAME of a FAXPak NetShare phone
book file. When a user runs fpnetfax.exe, this phone
book is loaded by default. The user has the ability to
select other phone books.
Example: PhoneBook = F:\JEFF\PRIVATE.FSB
FROMNAME = text (30 char max) default = none
-------------------------------------------------------
This text is inserted into the "FROM" field on the
display. The user can change this.
Example: FromName = Jeff Hofstetter
Example: FromName = %UNAME% (parameter replacement!)
STDFILES = full file name default = none
-------------------------------------------------------
The FULL FILE NAME of a standard files list. See the
section on using Standard Files.
────────────────────────────────────────────────────────────
27
Chapter 5 Customizing FAXPak NetShare
────────────────────────────────────────────────────────────
Example: StdFiles = F:\DATA\BROCHURE.DAT
NOTIFY = command default = none
-------------------------------------------------------
This is a NETWORK message command that will be run if
this fax fails to complete. It is mainly designed to be
used to notify each user of failed faxes. On a Novell
network this would be a "SEND ..." command. On a
Lantastic network, it would be a "NET SEND ..."
command. For example:
Novell example:
Notify = SEND "Fax to $I failed" TO JEFF
Lantastic example:
Notify = NET SEND * "Fax to $I failed" * JEFF
USERID = text (8 char max) default = none
-------------------------------------------------------
This entry may be used to provide some additional
privacy for your users. If this entry is used
(UserID=JEFF for example), then each log entry will be
compared against this entry and if the USERID in the
log entry is different, it will not be displayed. This
is mainly useful if you want to have a common log file
for the entire network. Note that this ALSO affects the
pending log. Users will ONLY see pending entries that
are for their USERID entry.
Example: UserID = JEFF H
────────────────────────────────────────────────────────────
28
C H A P T E R 6
S T A N D A R D F I L E S
────────────────────────────────────────────────────────────
If your faxing requirements include the need to
frequently send the same set of files, you may be able
to make use of the "standard files" feature of
fpnetfax.exe.
To implement this feature, simply include in
fpnetfax.ini the command
StdFiles = < file name >
Where < file name > is the FULL file name of a
specially prepared file which is described below.
If this command line is included in fpnetfax.ini, then
when a user runs fpnetfax.exe, pressing the F4 function
key pops up the list of standard files for the user to
select from.
The "standard files" list is a plain text file
containing one line identifying the directory where the
standard files are stored and then one line for each of
the standard files. Here's an example:
C:\STDFILES
FILE1.DCX Price List
FILE2.DCX General product brochure
PROD1001.PCX Product 1001 brochure
Note that the FIRST line is the directory. Each line
after the first is a file name followed by at least one
space then a short description of the file.
When the user pops up the standard files list, the file
name and the short description are displayed.
This feature allows you to place the files to be sent
on the server PC hard disk thus reducing the network
traffic required to copy the files from the network
drive to the fax server PC.
────────────────────────────────────────────────────────────
29
C H A P T E R 7
E X T E R N A L P R O G R A M S
────────────────────────────────────────────────────────────
FAXPak NetShare has the ability to integrate other
programs (called external programs) into it's
operation. This feature has two functions:
1. Integrate an external program to PRINT faxes as they
are received.
2. Integrate an external program to CONVERT outgoing
faxes from one format into another that is suitable for
faxing via an Intel fax board.
Note that these external programs ARE NOT included with
FAXPak NetShare but are purchased separately (as
desired) then integrated into the server.
EXTERNAL PROGRAM REQUIREMENTS
There are a few requirements before a program can be
integrated with FAXPak NetShare. In general, the
program must be capable of "command line" operation and
must return a result code indicating whether or not the
program completed successfully. These are fairly
routine requirements. If you are not sure if a program
meets these requirements, consult the maker of the
program.
COMMAND LINE operation means that the program can
perform its task without the need to interact with a
user. This is normally done by supplying the program
with command line arguments. For example, consider the
HYPOTHETICAL program FCONVERT.EXE. This program
converts files that are designed for a laser printer
into a file that can be faxed by an Intel fax board (a
"DCX" file). In order for this program to operate, you
must provide the name of the file that is to be
converted (the input file) AND the name of the file
that is to be created (the output file). For example:
FCONVERT myfile.pcl myfile.dcx
'myfile.pcl' is the input file and 'myfile.dcx' is the
output file. In addition to the input and output file,
our hypothetical program also allows a command line
option to prevent any screen display while it is
converting the file. This hypothetical option is /Q. So
our "command line" is this:
FCONVERT myfile.pcl myfile.dcx /Q
────────────────────────────────────────────────────────────
30
External Programs Chapter 7
────────────────────────────────────────────────────────────
When FCONVERT runs, it converts the input file to the
output file without displaying any messages. When the
program is over, it returns a "result" code that
indicates whether or not the conversion was successful.
In our hypothetical program, the result code returned
is 0, if the process was successful, and 1 if it was
not. (By the way, these result codes are the MOST
common ones for command line programs).
HOW FPNSHARE.EXE RUN AN EXTERNAL PROGRAM
Assuming that the external program setup is correct,
FAXPak NetShare runs the program by trying to swap
itself (FPNSHARE.EXE) out to EXPANDED memory or to
disk. It then runs the external program. This process
could fail for the following reasons:
Not enough memory. If FPNSHARE.EXE can't be saved
to expanded memory and can't be swapped to disk,
it remains in memory and tries to run the external
program. If there is not enough available memory
to do this, the process will fail.
Program not found. The external program must be
"locatable" by FPNSHARE.EXE. If you provide the
full path name to the program it should be
locatable. If the program is located in a
directory that is included in your DOS PATH, it
should be locatable. If the program is located in
the current directory (as FPNSHARE.EXE runs), it
should be locatable.
External program error fails. If the external
program can't locate the file to convert, or some
other type error, the whole process will fail.
INFORMATION REQUIRED TO INTEGRATE AN EXTERNAL PROGRAM
In order to integrate an external program, you need to
know the following information:
The program name (for example: FCONVERT.EXE).
The required and optional program arguments.
The file extension that will be used to "trigger" the
external program. For example, our hypothetical program
FCONVERT is able to convert files designed for laser
printers. You may want to use the file extension PCL to
────────────────────────────────────────────────────────────
31
Chapter 7 External Programs
────────────────────────────────────────────────────────────
indicate that a particular file is a laser print file.
When the server program finds a file with the extension
PCL, it then runs the external program that handle this
file extension.
Once you determine this information, you must then edit
the FPNSHARE.INI file to inform the fax server.
MODIFYING THE FPNSHARE.INI FILE
There are two special entries that are allowed in the
FPNSHARE.INI that deal with external programs:
CONVERT =
PRINT =
The Convert key word is used to designate an external
program that converts files from one type to a DCX file
for faxing by the Intel fax board. Multiple CONVERT
entries are permitted in FPNSHARE.INI.
The Print key word is used to integrate an external
program that can print a DCX file. When the Intel fax
board receives a fax (not a file transfer from another
Intel fax board), it receives the file as a DCX file.
The fax server software automatically saves the
received file using a unique file name with the DCX
file extension. After the file is saved, the external
program is run. Only one PRINT= entry is used in
FPNSHARE.INI.
CONVERT= entry
The format of the CONVERT= entry is
CONVERT=ext, SAVESCREEN, VERBOSE, program, args
where 'ext' is the file extension that designates a
file that is to be converted.
SAVESCREEN is optional and if included, the fax server
display screen is saved before running the external
program and then restored after the external program
runs. This allows for external programs that display
output while they run. If your external program
displays any output, be sure to use SAVESCREEN
otherwise, the fax server display will be overwritten
by any display output from the external program
────────────────────────────────────────────────────────────
32
External Programs Chapter 7
────────────────────────────────────────────────────────────
VERBOSE is optional and if included, a message is
displayed indicating that the fax server is running and
external program and, when the external program
completes, how long the external program took to do its
job.
'program' is the name of the external program. You can
include a full path name for the program OR just the
program name if the program is in the current directory
(of the fax server) or if the external program is
located in a directory that is included in your DOS
PATH statement. Some programs are finicky about where
they run from and about any files that are required.
Check the external program documentation for special
requirements.
'args' consists of the REQUIRED special symbols "$I"
and "$O" (which are replaced by the actual input and
output file names when the external program runs) plus
any unique options required by the external program.
The external program may expect to have the optional
arguments BEFORE the input and output file names or it
may expect the optional arguments AFTER the input and
output names. See the examples below.
PRINT= entry
The format of the PRINT= entry is the same as the one
for CONVERT=. In fact, everything is IDENTICAL except
for the 'args' setting.
The 'args' setting consists of the REQUIRED "$I"
symbols plus any options required by the external
program. This differs from the CONVERT= setting because
the "$O" symbol is not used. There is no OUTPUT file
when printing. See the examples below.
EXAMPLE .INI ENTRIES
This example of the CONVERT= entry in FPNSHARE.INI uses
our HYPOTHETICAL conversion program FCONVERT.EXE.
CONVERT=PCL, SAVESCREEN, VERBOSE, FCONVERT.EXE, $I $O
This entry translates to: If a file with PCL as the
file extension is encountered, run the program
FCONVERT.EXE to translate the file to a DCX file for
faxing. Before running FCONVERT, save the fax server
display screen. Display messages on the fax server
────────────────────────────────────────────────────────────
33
Chapter 7 External Programs
────────────────────────────────────────────────────────────
screen concerning how long FCONVERT took to do the file
conversion. When running FCONVERT, supply two command
line arguments consisting of the input file name and
the output file name.
To (perhaps) make this clearer, assume that a user
decides to fax a file called "MEMO.PCL". Since the file
has PCL as the file extension, the fax server will run
the FCONVERT program. The FCONVERT program will be run
with the following command:
FCONVERT C:\OUTBOX\MEMO.PCL C:\FAX\91731003.DCX
Note that the "$I" symbols was replaced with the full
file name of the file to be faxed and the "$O" symbol
was replaced by the file name of the output file. The
fax server creates a UNIQUE output file name for each
file being translated. This prevents accidentally
erasing files.
If FCONVERT allowed a special option (perhaps "/Q")
that inhibits screen output while it processes, you
might change your CONVERT= entry to this:
CONVERT=PCL,FCONVERT.EXE, /Q $I $O
Note that SAVESCREEN was removed. Since FCONVERT was
run with the /Q option, no screen output would over
write the fax server display screen so saving the
screen wasn't necessary. This example also shows the /Q
before the $I and $O symbols. Each external program may
have different placement rules for file names and
options.
Here's an example of the PRINT= entry using the program
FPPRINT.EXE which is included with FAXPak Advanced
Edition (available from the author of FAXPak NetShare).
PRINT=DCX, SAVESCREEN, C:\FAXPAK\FPPRINT.EXE, $I $O
This will run FPPRINT.EXE (note the use of the full
path name), save the fax server screen, and pass the
input and output file names.
────────────────────────────────────────────────────────────
34
External Programs Chapter 7
────────────────────────────────────────────────────────────
TROUBLESHOOTING EXTERNAL PROGRAMS
If your external program doesn't run as you think it
should, try these tips:
Include the VERBOSE key word to see if the fax server
actually tries to run your program. A message is
displayed when the server attempts to run an external
program. If you never see the message, check your entry
in FPNSHARE.INI to see that it is properly designed.
Especially note the file extension you are looking for.
For example, if your FPNSHARE.INI entry shows the file
extension ".PCL", you will have problems. DO NOT
include the period! Check to see that the files you are
expecting to convert with the external program do in
fact have the correct file extension.
If the process starts but fails, check to make sure
that the external program is being found (DOS PATH,
current directory, full path provided). Also check that
you have provided the $I and $O symbols in the proper
position required by the external program.
────────────────────────────────────────────────────────────
35
A P P E N D I X A
C U S T O M E R I N F O R M A T I O N
────────────────────────────────────────────────────────────
COPYRIGHT
FAXPak (tm) NetShare, including all supporting documentation
and programs, is Copyright Jeff Hofstetter 1989-1991. All
Rights Reserved.
Copying of any of the programs or documentation is
prohibited except that you may make copies of the program
disk for archive purposes.
LICENSE
FAXPak (tm) NetShare server programs (FPNSHARE.EXE and
FPNSTSR.EXE) are licensed for use on a single computer with
a fax board installed. The client programs (FPNETLOG.EXE and
FPNETFAX.EXE) are licensed for use on any number of
computers communicating with a FAXPak NetShare server.
WARRANTY
The programs contained in FAXPak are provided "AS IS"
without warranty of any kind, either express or implied,
including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose. The
entire risk related to the performance of the programs is on
you.
In no event will I be liable to you for any damages
(including incidental or consequential damages) arising out
of the use of the included programs.
All that said, within sixty days of paying the license fee,
I will return your license fee (less any shipping charges)
for any reason. Simply return the product with a note
requesting a refund and you will receive it via return mail.
CUSTOMER SUPPORT
Registered users of FAXPak NetShare may obtain technical
assistance by calling 303.440.7683 during normal business
hours (USA Mountain Time Zone).
You may also send a fax (or fax board file transfer) at the
same number 24 hours a day.
────────────────────────────────────────────────────────────
36
Customer Information Appendix A
────────────────────────────────────────────────────────────
If you discover any bugs please notify me via phone or fax.
Every effort will be made to solve the problem quickly and a
fix provided via FAX DELIVERY.
────────────────────────────────────────────────────────────
37
A P P E N D I X B
P R O G R A M M I N G I N T E R F A C E
────────────────────────────────────────────────────────────
FAXPak NetShare performs a simple task: it periodically
checks in a specified directory looking for fax
requests from users. These requests are know as "fax
control files". This appendix documents the fax control
file so that anyone writing application programs can
create these files to give the application the ability
to send faxes on a network.
The fax server program also creates log files which
reflect the results of faxes sent and received. The
format of the log files is also documented here.
GENERAL INFORMATION
Fax control files and log files are plain text files
(no control characters or word processing codes are
permitted).
Each file consists of several (possibly many) lines,
each line is terminated by the standard DOS convention
of carriage return/line feed (decimal 12, 10 or hex 0D,
0A). Any line in a file that has a semi-colon as the
first non-space character on a line is considered a
comment line and is ignored. Blank lines are permitted.
Each line in the file consists of a keyword and
(usually) an equal sign followed by a value (or
values). For example, in a fax control file (which have
.FAX as the file extension by default), here are two
lines:
FROM=Jeff Hofstetter
PHONE=1 303 440 7683
The key words are FROM and PHONE and the values are
"Jeff Hofstetter" and "1 303 440 7683".
Some of the key word entries allow multiple occurrences
within the fax control file: FILE=, SFILE=, STDFILE=,
ENTRY=, and COMMENT=. You include as many occurrences
as are necessary to get the job done!
Since the server operates in a network environment, it
tries to use network sharing functions whenever
possible. Your program should also exercise caution
when opening, reading, and writing files that are to
interface with FAXPak NetShare.
────────────────────────────────────────────────────────────
38
Programming Interface Appendix B
────────────────────────────────────────────────────────────
If your program creates fax control files, you should
be careful not to provide badly formatted values. The
fax server software expects valid values!
FAX CONTROL FILES
Fax control files are created by FPNETFAX.EXE and are
processed by FPNSHARE.EXE and FPNSTSR.EXE (the TSR
server program). By default, these files have .FAX as
the file extension.
Fax control files are placed in a particular directory
so that the server process can locate them. By default
this directory is \FAXPAK\REQ on a network drive.
Following are all of the valid key words and values for
use in fax control files.
TO=text (max 31 characters)
-------------------------------------------------------
The "to" name on the fax.
FROM=text (max 31 characters)
-------------------------------------------------------
"From" name on the fax.
PHONE=text (max 47 characters)
-------------------------------------------------------
Phone number to dial. You can include commas in the
dial string to allow for pauses. Other special
characters are also permitted. See the Intel
documentation.
DATE=mm/dd/yyyy
-------------------------------------------------------
Date to send the fax. Note that you must include 4
digits for the year for example: DATE=08/01/1991.
────────────────────────────────────────────────────────────
39
Appendix B Programming Interface
────────────────────────────────────────────────────────────
TIME=hh:mm (or h:mm p)
-------------------------------------------------------
Time to send the fax. Two time formats are accepted: 24
hours time (for example: TIME=23:30) and the 12 hour
with AM/PM character: TIME=11:30pm. A time without the
am/pm indicator is assumed to be a.m.
TYPE=FINE, STD, CCP, FAX1, FAX2, or FILE
-------------------------------------------------------
Specifies the transmission mode. FINE (and FAX1) are
fax fine resolution send. STD (and FAX2) are fax
standard resolution. CCP (and FILE) is the Intel fax
board file transfer mode.
LOGO=full file name
-------------------------------------------------------
This is the name of a PCX logo file (as defined by the
Intel documentation) that will be placed at the top of
a standard Intel fax cover page.
TAGFIELD=text (max 63 characters)
-------------------------------------------------------
This can be any 63 characters of text you desire. It
might be useful to your application to identify faxes
created by your process.
TEXTSIZE=NORMAL or SMALL
-------------------------------------------------------
The Intel fax boards have the ability to take a
standard plain text file (ASCII) and convert it to a
faxable graphic image file. You can select which size
text font to use during this process. NORMAL is 80
characters per line, 66 lines per page (8.5 x 11 inch
page size). SMALL is 132 columns per line and 88 lines
per page. Remember, this setting has NO effect on any
fax send except for sending plain text (ASCII) files as
fax sends.
────────────────────────────────────────────────────────────
40
Programming Interface Appendix B
────────────────────────────────────────────────────────────
COMMENT=text (80 chars max)
-------------------------------------------------------
The standard Intel fax cover page has room for about 30
lines of comments (each line is 80 chars wide). If you
want to put comment text on the cover page, include a
COMMENT=text entry for each line of text. If you
attempt to put more than 30 lines of COMMENT= entries,
the excess lines are discarded.
RETRY=number
-------------------------------------------------------
You can specify how many times THIS particular fax
should be retried.
LOGFILE=filename (max 8 chars)
-------------------------------------------------------
This entry is the (up to ) 8 character file name (no
file extension) of the log file where the results of
THIS particular fax will be recorded.
ENTRY=to name | phone#
-------------------------------------------------------
If you are sending the same file (or set of files) to
multiple destinations, you create an ENTRY= for each
person receiving the fax. Note that the TO name and the
phone number MUST be separated by the vertical bar
character "|".
PAGELENGTH=inches (no partials)
-------------------------------------------------------
If you are sending a plain text (ASCII) file as a fax
transmission (not a file transfer), you can set the
page length you want. For example, to send a plain text
file on legal size paper: PAGELENGTH=14
NOTIFY=command (80 chars max)
-------------------------------------------------------
If you would like to send a message to the sender of
the fax if this particular fax fails to complete, you
can enter the DOS program that sends the message. On a
Novell network, you would use the SEND command. You can
────────────────────────────────────────────────────────────
41
Appendix B Programming Interface
────────────────────────────────────────────────────────────
include the special symbol $I in your command string.
This symbol will be replaced with information about the
fax when your message is sent. For example:
SEND "Fax to $I failed" to JEFF
This command line would be run IF this fax failed to
complete. When the message is sent, the $I would be
replaced with information about the fax.
FILE= ENTRIES IN THE FAX CONTROL FILE.
A small bit of discussion is necessary to understand
how the next three key word entries are used in the fax
control file.
There are three FILE entries permitted: FILE=, SFILE=,
and STDFILE=. Each one serves a different purpose.
Please study the individual entries closely!
FILE=file name
-------------------------------------------------------
This entry is used for "documentation" purposes only.
It is the file name (or document name) of the ORIGINAL
file selected by the user to be faxed. This file name
is the one that will appear in the fax log of this
event. This entry by itself IS NOT SUFFICIENT TO
IDENTIFY THE FILE TO BE FAXED!
SFILE=full file name
-------------------------------------------------------
This entry (full path name) is the name of the file
that is ACTUALLY FAXED by the server. IMPORTANT! The
SFILE entry is DELETED from the disk when the fax is
completed (either successfully or not). The reason for
this double entry system is that the client program
FPNETFAX.EXE (which is users run to make fax requests)
allows users to select files to send. FPNETFAX then
COPIES the original files to an "outbox" directory.
These copies become SFILE= entries so deleting them
after the fax completes is useful.
If you DO NOT WANT YOUR FILES DELETED, DO NOT USE
SFILE=!!! See STDFILE= instead.
────────────────────────────────────────────────────────────
42
Programming Interface Appendix B
────────────────────────────────────────────────────────────
STDFILE=full file name
-------------------------------------------------------
This entry serves the same purpose as the SFILE= entry
except that the file IS NOT DELETED when the fax is
completed. This entry was originally designed for use
with the "standard files" feature of FPNETFAX, but may
also be used to indicate that a file should be faxed
but not deleted.
CONCLUDING REMARKS ABOUT THE FILE= ENTRIES.
To wrap up, you generally want to have TWO of the FILE=
entries in your fax control file. FILE= and SFILE= OR
FILE= and STDFILE=.
USERID=text (8 chars max)
-------------------------------------------------------
If you include this entry in your fax control file, the
"text" provided will be embedded in the fax log entry
for this fax. When someone views a fax log containing
this event, they will ONLY be able to display the log
entry if their USERID= setting in their FPNETLOG.INI
matches this text. This may be used to provide security
if desired.
PRIORITY=0 or 1
-------------------------------------------------------
The server process processes fax requests and schedules
them as indicated by the users. Each fax may get a
priority number of 0 or 1. All priority 0 faxes get
sent ahead of priority 1 faxes no matter when they are
submitted. This feature was included as a result of the
need to "get a fax out fast" even if several others are
waiting in queue to be sent. Obviously, giving every
fax a priority 0 will defeat this scheme.
FAXPAK NETSHARE LOG FILES
The server programs create and maintain log files in a
specific network directory. By default this is
\FAXPAK\LOG on a network drive.
────────────────────────────────────────────────────────────
43
Appendix B Programming Interface
────────────────────────────────────────────────────────────
Depending on needs, there may be one or more log files
maintained. They are all maintained in the same
directory.
Below are all of the entries that may be found in the
log files.
[FaxEvent]
-------------------------------------------------------
This entry indicates the beginning of a fax log record.
All entries below this to the next [FaxEvent] are part
of the same fax event.
ID=number
-------------------------------------------------------
This is the decimal number assigned by the Intel fax
software. Each fax gets a unique number.
ETYPE=RECV or SEND
-------------------------------------------------------
Designates whether an event is a send or receive.
TTYPE=Fax Std, Fax Fine, or FileTrf
-------------------------------------------------------
Indicates the transmission type.
DATE=mm/dd/yyyy
-------------------------------------------------------
Date the transmission occurred
TIME=hh:mm
-------------------------------------------------------
Time the transmission occurred. This is always given in
24 hour time.
────────────────────────────────────────────────────────────
44
Programming Interface Appendix B
────────────────────────────────────────────────────────────
FROM=sender name
-------------------------------------------------------
On a fax transmission, this will normally be the same
as the remote id (see later). On a file transfer, it
shows the send name as specified by the sender.
TO=to name
-------------------------------------------------------
The "to" name as specified by the sender. May also be
the phone number that was called.
PHONE=phone number
-------------------------------------------------------
The phone number that was dialed.
STATUS=Complete or Error
-------------------------------------------------------
Self-evident!
REMOTEID=text
-------------------------------------------------------
On a send event, the remote fax machine sends its
internal ID as verification of the transmission. Most
fax machines have their OWN phone number as an ID, but
some brands of fax machines allow alpha-numeric codes
to be entered.
TAGFIELD=text
-------------------------------------------------------
On Intel fax board to fax board transfers, the send can
embed some "tag" text in the fax. The receiver can then
examine events to determine if this "tag" text exists.
Might be useful for custom applications.
DURATION=hh:mm:ss
-------------------------------------------------------
The duration of the fax transmission/reception.
────────────────────────────────────────────────────────────
45
Appendix B Programming Interface
────────────────────────────────────────────────────────────
ERRMSG=message
-------------------------------------------------------
If the fax failed to complete (Status=Error), this
entry will have the error message generated.
RETRIES=number
-------------------------------------------------------
How many retries were made before successful completion
or "giving up". A fax that was completed on its first
attempt will have RETRIES=0.
NUMPAGES=number
-------------------------------------------------------
For fax events, this is the number of fax pages that
were sent/received. For Intel fax board file transfers,
this is the number of files that were transferred.
ERRORS=number
-------------------------------------------------------
This records the number of "blocks" that had to be re-
transmitted because of errors during the fax. The fax
process corrects errors by re-sending information. If
you have lots of errors on many of your faxes, you may
need to have your phone lines checked.
FILE=file name
-------------------------------------------------------
This is the file name(s) that were sent or received.
────────────────────────────────────────────────────────────
46
